// Copyright (c) Microsoft Corporation. All rights reserved.

using System;
using System.Collections.Generic;
using System.Text;

namespace Microsoft.TeamFoundation.Migration.Toolkit
{
    /// <summary>
    /// The interface that version control end points must implement.
    /// </summary>
    [System.Diagnostics.CodeAnalysis.SuppressMessage("Microsoft.Design", "CA1040:AvoidEmptyInterfaces")]
    public interface IVersionControlEndpoint
    {
    }

    /// <summary>
    /// The version control end point interface that supports Tfs link handler.
    /// It implements related methods to support latest version and versioned item.
    /// </summary>
    public interface IVersionControlLinkableEndPoint : IVersionControlEndpoint
    {
        /// <summary>
        /// Given the artifact uri, returns the latest versioned item path on the system.
        /// The artifact uri is in the format of vstfs:///VersionControl/LatestItemVersion/item_id
        /// </summary>
        /// <param name="artifactUri">artifactUri to be queried</param>
        /// <returns>The server path of the item. Return null is the item cannot be found.</returns>
        [System.Diagnostics.CodeAnalysis.SuppressMessage("Microsoft.Design", "CA1054:UriParametersShouldNotBeStrings", MessageId = "0#")]
        string GetPathFromLatestItemVersion(string artifactUri);

        /// <summary>
        /// Given the artifact uri, returns the versioned item path and changeset id on the system
        /// the artifact uri is in the format of vstfs:///VersionControl/VersionedItem/path_changesetid_deletionid
        /// </summary>
        /// <param name="artifactUri">artifactUri to be queried</param>
        /// <param name="path">Out value, the server path of the versioned item. Null if the item cannot be found.</param>
        /// <param name="changeId">Out value, the change id of the versioned item. Null if the item cannot be found.</param>        
        [System.Diagnostics.CodeAnalysis.SuppressMessage("Microsoft.Design", "CA1054:UriParametersShouldNotBeStrings", MessageId = "0#"), System.Diagnostics.CodeAnalysis.SuppressMessage("Microsoft.Design", "CA1021:AvoidOutParameters", MessageId = "2#"), System.Diagnostics.CodeAnalysis.SuppressMessage("Microsoft.Design", "CA1021:AvoidOutParameters", MessageId = "1#")]
        void GetPathFromVersionedItem(string artifactUri, out string path, out string changeId);

        /// <summary>
        /// Get latest item id from path on the system. Return null if the item cannot be found on system.
        /// </summary>
        /// <param name="path">the path of the item</param>
        string GetLatestItemIdFromPath(string path);

        /// <summary>
        /// Get the revisioned item artifact uri from server path and changeid on the system. 
        /// Return null if the item cannot be found on the system.
        /// </summary>
        /// <param name="path">the path of the item</param>
        /// <param name="changeId">changeId of the item</param>
        /// <returns>The artifact uri of the item found</returns>
        string GetVersionedItemArtifactFromPathAndId(string path, string changeId);

        /// <summary>
        /// Given a path, find the mapped path according to session mappings
        /// </summary>
        /// <param name="path">the path to be searched</param>
        /// <param name="session">the version control session</param>
        /// <param name="useTarget">Given path is source path if this value is set to true</param>
        /// <returns></returns>
        string FindMappedPath(string path, VersionControlSession session, bool useSource);
    }
}
